=========================================================================
ISTRUZIONI e SPECIFICHE per il TERZO FRAMMENTO del PROGETTO di LCS 08/09
========================================================================

Il progetto ZTL e' suddiviso in  tre frammenti.
Il terzo e' descritto in questo README.

Questo frammento prevede la realizzazione di due programmi multithreaded: 

- permserver: che mantiene l'albero dei permessi attivi nella ZTL

 - ztl: che si occupa di ricevere sullo standard input un insieme di passaggi
   registrati nella ZTL e di verificarne la validita' interagendo con 
   "permserver" 

------------------------------------------------
Estrarre il materiale dal KIT di progetto
------------------------------------------------
Creare una directory temporanea, copiare lcsZTL_kitf3.tar  
nella directory e spostarsi nella directory appena creata. Es.

$$ mkdir Frammento3
$$ mv lcsZTL_kitf3.tar Frammento3
$$ cd Frammento3

S-tarare i file del kit

$$ tar xvf lcsZTL_kitf3.tar 
questa operazione crea nella directory corrente una directory "ZTL" che
contiene:

$$ ls ZTL
Doc/ Src/ README ztl0809.pdf

Src/ contiene sorgenti, header, Makefile tests etc

========================================================================
ISTRUZIONI per la realizzazione 
========================================================================

Le specifiche per la realizzazione dei due programmi si trovano nel file  
ztl0809.pdf. 

Deve inoltre essere realizzata una libreria di comunicazione via socket AF_UNIX il cui header e' specificato in 

Src/lcscom.h

Tale file contiene i prototipi delle funzioni da
realizzare, i tipi di dato e le define relative ai messaggi scambiati nel protocollo usato fra ztl e permserver.

E' possibile generare la documentazione doxygen per questo file invocando

  bash:~$ make docu

nella directory Src/ dopo l'esecuzione visualizzare 

../Doc/html/index.html

con un qualsiasi browser.

Il kit fornisce tre diversi test per verificare il funzionamento complessivo del progetto:

1)TEST-1 il primo test verifica la corretta attivazione dei programmi ed il parsing degli argomenti. E' attivabile con

$ make testf1

2)TEST-2 il secondo test verifica la corretta elaborazione dello stream dei 
passaggi in ztl.  E' attivabile con

$ make testf2

3)TEST-3 il terzo test verifica la gestione dei segnali, il refresh periodico dei permessi nel server permserver e la generazione delle multe con "mailscript" oggetto del secondo frammento.  E' attivabile con

$ make testf3

------------------------------------------------------------------
File/Dir contenuti in Src
------------------------------------------------------------------

$$ ls Src/

README-3	Makefile	FINALDATA/
testparse	testfunz	testsig
lcscom.h	passaggi
passaggi32



-----------------------------------------------
Descrizione del contenuto dei file 
-----------------------------------------------
README-3		: questo file

lcscom.h
			: tipi e prototipi delle funzioni da realizzare
			  per la libreria di interazione
			  (modificare solo aggiungendo
			  campi/definizioni/prototipi senza MODIFICARE/ELIMINARE
			  quelli gia' esistenti)

testparse
testfunz
testsig
			: script bash di test del progetto
                          (NON MODIFICARE)

passaggi		  : eseguibile che genera lo stream di passaggi 
passaggi32		    ZTL da elaborare (64 bit) per esecuzione su
			    macchine a 32 bit copiare in "passaggi" il 
			    file passaggi32

Makefile		: makefile per il test del frammento e la
			  consegna 
			  (MODIFICARE SOLO nelle parti richieste, vedi
			  commenti nel file)

FINALDATA/		  Directory che contiene i vari file di dati/controllo
			  usati nei test

------------------------------------------------
Cosa deve essere realizzato
------------------------------------------------

Oltre a quanto realizzato nel primo e nel secondo frammento il terzo prevede la realizzazione della libreria di comunicazione "lcscom", del programma "ztl" e 
del programma "permserver". Permserver utilizza la libreria libztl.a.

Il funzionamento della libreria e dei programmi e' specificato nel file ztl0809.pdf.

Il Makefile deve essere esteso ocn opportuni target per la compilazione e la generazione degl ieseguibili ztl e permserver. Inoltre, il Makefile contiene una variabile 
FILE_DA_CONSEGNARE3
che deve contenere tutti i file necessari alla corretta esecuzione del progetto. In particolare,
-- devono essere riconsegnati anche i file relativi ai primi 2 frammenti
-- deve essere consegnata anche una relazione 
   (secondo le specifiche in ztl0809.pdf) formato PDF

------------------
Come procedere :
-----------------

0) leggere attentamente il README, le specifiche e capire il funzionamento degli esempi forniti

1) implementare le funzioni richieste in lcscom.h
   ed effettuare testing preliminare utilizzando procesi di test sviluppati
   allo scopo

2) realizzare ztl & permserver e testarli

3) effettuare il test complessivodel terzo frammento 
   con i test forniti dai docenti

4) Effettuare il test finale complessivo. E' necessario
  prima settare la variabile di 
  ambiente MALLOC_TRACE in modo che contenga "./.mtrace" e poi
  procedere al test invocando il target "test", cioe' eseguire:

       bash:~$ export MALLOC_TRACE="./.mtrace"
       bash:~$ make testfinale

       questo provoca l'invocazione dei test di tutti i tre frammenti.

  NOTA: (1) tutti i file sviluppati per la soluzione si devono trovare nella
  directory Src/
  (2) E' importante che il test venga effettuato solo su
  un programma gia' funzionante altrimenti i risultati possono essere di
  difficile interpretazione, fuorvianti o inutili.


5) preparare la documentazione: ovvero commentare adeguatamente il/i file che
   contengono la soluzione  ed inserire una intestazione contenente il nome
   dello sviluppatore ed una dichiarazione di originalita' 

   /** \file pippo.c
       \author Nino Bixio
     Si dichiara che il contenuto di questo file e' in ogni sua parte opera
     originale dell' autore.  */

     Non e' richiesto di preparare anche la documentazione formato
     doxygen. Chi volesse farlo e' invitato a leggere il  README.doxigen
     del primo frammento.

5) copiare il file "gruppo.txt" con nome e dati fornito nei frammenti precedentiall'interno della directory Src/

6) consegnare il file ESCLUSIVAMENTE eseguendo

      bash:~$ make consegna

   e seguendo le istruzioni. Anche in questo caso occorre  che la variabile
   MALLOC_TRACE sia settata  a "./.mtrace".  
   Per la consegna e' necessaria l'utility "mpack" installata solo nelle
   macchine dei laboratori H, M ed I. Per consegne da altre macchine e'
   possibile scaricare il binario di 'mpack' dal sito del corso oppure
   semplicemente allegare il tar file creato dal make consegna ad un
   normale messaggio di mail con subject "lcs09: consegna progetto finale".

  Tutte le consegne verranno confermate con un messaggio entro 2/3
   giorni. In caso questo non si verifichi contattare il docente.
  

 ---------------------------------------
 NOTE IMPORTANTI: LEGGERE ATTENTAMENTE
---------------------------------------

1) gli eleborati non consegnati con "make consegna" o con un tar non
creato da "make consegna" non verranno accettati

2) tutti gli elaborati verranno confrontati fra di loro con tool automatici
   per stabilire eventali situazioni di PLAGIO. Se tali situazioni si
   verificheranno *tutti* gli elaborato coinvolti verranno annullati con
   conseguente perdita del bonus. 

3) Tutti gli studenti coinvolti in un episodio di PLAGIO comprovato dovranno
   re-implementare il frammento incriminato e saranno sottoposti ad una prova
   orale supplementare. In caso di recidive verranno esclusi dalla
   possibilita' di sostenere l'esame per TUTTO IL RESTO DELL'ANNO ACCADEMICO
   IN CORSO.

4) Chi in sede di orale risulta palesemente non essere l'autore del software
   consegnato in uno dei frammenti verra' escluso dalla possibilita' di
   sostenere l'esame per TUTTO IL RESTO DELL'ANNO ACCADEMICO IN CORSO.

5) Tutti i comportamenti scorretti ai punti 3 e 4 verranno segnalati
   ufficialmente al presidente del corso di laurea, che si riserva di
   decidere azioni disciplinari supplementari a quelle sopra descritte.

----------------------------
 VALUTAZIONE DEL FRAMMENTO:
----------------------------

Gli studenti che consegnano una versione funzionante e ragionevolmente
corretta del frammento entro la data di scadenza accumulano un bonus di 2
punti che verra' sommato al voto finale (vedi lucidi lezioni ed
esercitazioni).

La qualita' del codice consegnato per il primo frammento verra' valutata come
parte del progetto finale e contribuira' alla votazione assegnata al progetto.
Eventuali caratteristiche in piu' rispetto a quelle strettamente richieste
dalle specifiche date qua (es. documentazione doxygen, 
bilanciamento alberi in ptree) verranno valutate in questa sede.







